home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr49 / ppt100.zip / PPT.DOC < prev    next >
Text File  |  1993-05-01  |  49KB  |  1,014 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                           GL Software Services
  11.  
  12.                                  PPT.DOC
  13.  
  14.                        Version 1.0  --  April, 1993
  15.  
  16.          Copyright (c) 1993, Gary L. Levine, All Rights Reserved
  17.              4255 South Buckley Road #295, Aurora CO, 80013
  18.                            303.840.2840  (BBS)
  19.                           CompuServe: 70152,253
  20.                    Internet: 70152.253@compuserve.com
  21.  
  22.  
  23.  
  24.  
  25.  
  26.                          D O C U M E N T A T I O N
  27.                          =========================
  28.  
  29.  
  30.  
  31.  
  32.    Table of Contents
  33.    -----------------
  34.  
  35.    Introduction............................................    1
  36.    Quick Start / Tutorial..................................    3
  37.    Acknowledgements........................................    3
  38.    Registration............................................    4
  39.    Support and Feedback....................................    4
  40.    System Requirements.....................................    5
  41.    Disclaimer..............................................    5
  42.    Tutorial................................................    6
  43.        Configuration.......................................    6
  44.        Text / C Identifier Search..........................    8
  45.        Drives Usage........................................   11
  46.        Search and Replace Identifier.......................   12
  47.        Function Flow Analyzer..............................   14
  48.        Set Files Date / Time...............................   19
  49.    Misc Features...........................................   20
  50.        Startup Options.....................................   20
  51.        @ Files.............................................   20
  52.        Hotkeys.............................................   21
  53.        Help System.........................................   21
  54.    Troubleshooting.........................................   22
  55.        Limitations.........................................   22
  56.        Resetting the database..............................   22
  57.  
  58.  
  59.  
  60.    PPT Version 1.0  -  File PPT.DOC                            Page 1
  61.    ------------------------------------------------------------------
  62.  
  63.  
  64.    Introduction
  65.    ------------
  66.    PPT is a program I developed for my own use as a professionally
  67.    employed programmer.  Some of the capabilities of PPT are available
  68.    in commercial products, but not all together, and at a considerable
  69.    price.  Other features I have not found available anywhere, which is
  70.    why I decided to write them myself.  PPT is a set of utilities to
  71.    make programmers more productive.  Although PPT will be useful to 
  72.    all programmers, it will be especially useful to C programmers.  It
  73.    includes tools to analyze the structure of C programs, quickly find
  74.    (and rename if desired) identifier references, document function 
  75.    calls in your code, and many other features. It is divided into several 
  76.    modules:
  77.    
  78.     1) Text / C Identifier Search  -  A very enhanced grep-like utility
  79.        with the following features:
  80.                
  81.            Searches for pure text or C identifiers.
  82.            Searches for multiple text/identifiers and multiple
  83.                source modules in a single pass.
  84.            Case sensitive or insensitive searches.
  85.            Automatically searches included header files ... very
  86.                useful for quickly locating and displaying macro
  87.                definitions.
  88.            Scrollable output display with search items highlighted,
  89.                and direct links to your own editor and viewer programs.
  90.            Ability to save, recall, and rerun previous searches.
  91.            Reports to printer or file.
  92.  
  93.  
  94.     2) C Identifier Search and Replace  -  A utility to replace (rename)
  95.        a C identifier with another, with the following features:
  96.  
  97.            The same intuitive interface as the Text/C Identifier Search
  98.                module.
  99.            Works on multiple modules.
  100.            Automatically creates backup files.
  101.  
  102.    PPT Version 1.0  -  File PPT.DOC                            Page 2
  103.    ------------------------------------------------------------------
  104.    
  105.     
  106.     3) Function Analyzer  -  A utility to analyze the function call 
  107.        hierarchy of multiple C source modules, with the following features:
  108.        
  109.            A scrollable visual display of the function call tree, with
  110.                direct links to your own editor and viewer programs.
  111.            Split-screen views of (1) All functions in all modules, 
  112.                (2) All functions which call the function being examined, 
  113.                and (3) All functions not directly called by another.
  114.            Ability to exclude particular functions from the analysis by
  115.                listing them in an exclusions file.
  116.            Quick search capability to find a particular function in the
  117.                call tree.
  118.            Ability to "collapse" the path to a particular function call,
  119.                showing the direct sequence of calls which lead to it.
  120.            Ability to update your source files with comment headers
  121.                for each function showing what other functions call it.
  122.            Ability to save, recall, and rerun previous analyses.
  123.            Reports to printer or file, with numerous options.
  124.  
  125.  
  126.     4) Drives / Files Usage  -  A utility to display drive usage for
  127.        multiple logical drives, with the following features:
  128.            
  129.            Can display up to 15 logical drives per scenario, and
  130.                you can store up to 5 scenarios.
  131.            Numeric and graphic displays.
  132.            Number of files display.
  133.  
  134.  
  135.     5) Set Files Date/Time  -  A utility to set the date and time stamp
  136.        for multiple files at once.
  137.  
  138.  
  139.     6) In addition to the specific modules, the following general features
  140.        are incorporated:
  141.  
  142.            Context sensitive help available everywhere by pressing F1.
  143.            Command line options to allow a quick jump to a particular
  144.                module.
  145.            Shell to DOS feature with maximum memory available at the
  146.                DOS prompt.
  147.            Numerous hotkeys for quick jump to main menu, quick exit to
  148.                DOS, switch between function analyzer and search module,
  149.                and more.  Press Alt-H for a pop-up list.
  150.            "Sticky fields".  PPT always remembers the settings and where 
  151.                you were in a display the last time you ran a particular 
  152.                module.
  153.            Continuous progress displays for searches and analyses.
  154.            Runs well under DESQview, Windows, and OS/2.
  155.  
  156.    PPT Version 1.0  -  File PPT.DOC                            Page 3
  157.    ------------------------------------------------------------------
  158.    
  159.  
  160.    Quick Start
  161.    -----------
  162.    If you are the type (as many of us programmers are) who hate to read
  163.    manuals, and prefer to explore the software on your own, here's what
  164.    you need to know to do that.  Start the program by typing PPT.
  165.    After the welcome screen delay you will be presented with the main 
  166.    menu.  I suggest you start with "Configure System", and walk through
  167.    each of the 3 choices on that sub-menu.  Use the on-line Help (F1)
  168.    for an explanation of each screen.  Once you've configured, escape
  169.    back to the main menu and have at it.  You might also want to browse
  170.    through the help index.  Also try Alt-H for an explanation of the
  171.    hot keys.  
  172.  
  173.  
  174.    Tutorial
  175.    --------
  176.    I think the best way to show what PPT does and how you can use it
  177.    to become a more productive programmer, is through the use of a 
  178.    tutorial.  Please take a few minutes and walk through it.  Keep in 
  179.    mind that context-sensitive online help is always available by 
  180.    pressing F1.
  181.  
  182.  
  183.    Acknowledgements
  184.    ----------------
  185.    My thanks and gratitude to my fellow programmers at MIS, Inc. for
  186.    their enthusiastic reception of PPT, their thoughtful suggestions,
  187.    and their uncanny ability to crash it.
  188.  
  189.    Mr. Barry Nance kindly gave permission to use the source code from
  190.    his LIST file browser for the tutorial.  His program is described in 
  191.    the February/1993 issue of Byte Magazine, page 235.  You are free to
  192.    use, customize, distribute this source code as you wish, provided you
  193.    do not charge any money for it, and provided you leave the copyright
  194.    notice intact.  None of the registration fee for PPT pertains to
  195.    LIST.C.
  196.  
  197.    Without the love, patience, and encouragement I received from my wife 
  198.    Karen, this project would never have gotten out the door.
  199.  
  200.    PPT Version 1.0  -  File PPT.DOC                            Page 4
  201.    ------------------------------------------------------------------
  202.    
  203.  
  204.    Registration
  205.    ------------
  206.    PPT is distributed as shareware.  You are encouraged to share copies
  207.    of PPT with friends and associates, and to upload it to bulletin 
  208.    boards.  When distributing PPT, you MUST distribute only the archived
  209.    file PPT100.ZIP, to insure that all necessary files are included.
  210.    If you decide to keep and use PPT you must pay the appropriate 
  211.    registration fee.  Please fill out the form in REGISTER.FRM to register.
  212.    The form can be printed from inside PPT if you wish.  Select 
  213.    "Register!" from the main menu.  Registration buys you support (via 
  214.    CompuServe or our BBS), notification of future upgrades, and the warm 
  215.    feeling you get from knowing you are supporting the shareware concept!
  216.  
  217.    You only pay for this software ONCE (what a concept!).  Any and all
  218.    future upgrades are NO CHARGE once you're registered!
  219.    
  220.    This evaluation version is complete and identical to the registered 
  221.    version with the exception that you cannot bypass the initial welcome 
  222.    screen or the registration screen that appears on exit, and you cannot
  223.    save scenarios.
  224.  
  225.  
  226.    Support and Feedback
  227.    --------------------
  228.    Technical support is provided for registered users via CompuServe mail.
  229.    My user name and address are:  Gary L. Levine  70152,253.  I check
  230.    my mail daily and will respond promptly to all queries.
  231.  
  232.    Additionally, I run a small BBS for support of PPT.  The BBS phone
  233.    number is 303.840.2840.  The BBS software is Maximus 2.0 for OS/2.
  234.    Protocol is N81 (no parity, 8 data bits, 1 stop bit), and you are 
  235.    dialing into a Hayes Ultra96 modem.  You may leave mail, and you will 
  236.    always be able to find the latest version of PPT, along with notices 
  237.    of upcoming upgrades, etc.  Support is also available by mail of course.
  238.  
  239.    PPT is a program intended to make programmers more productive.  I have
  240.    used it almost daily for the last year and a half.  Many of its features
  241.    were inspired by the other programmers I work with.  I have a long list
  242.    of enhancements planned for PPT.  I would love to hear your comments,
  243.    suggestions, and (ouch!) criticisms.  Based of course on the response
  244.    that PPT generates, I hope to continually improve and expand on it.
  245.    Let me know what you think!
  246.  
  247.    PPT Version 1.0  -  File PPT.DOC                            Page 5
  248.    ------------------------------------------------------------------
  249.    
  250.  
  251.    System Requirements
  252.    -------------------
  253.    PPT requires an IBM compatible PC with an 80286 processor or better.
  254.    Since PPT is a collection of utilities for programmers writing code,
  255.    this minimal platform should not be a problem.  It would be hard to
  256.    imagine anyone doing development work these days on anything less 
  257.    powerful than this.  It has been tested with DOS 5.0, but should work 
  258.    all the way back to DOS 3.x.  It will run in a Windows DOS box 
  259.    (tested with 3.1), and a Virtual DOS Machine under OS/2 2.0.  Icons for 
  260.    Windows and OS/2 are provided.  Your CONFIG.SYS FILES setting should
  261.    be at least 30.
  262.    
  263.  
  264.    Disclaimer
  265.    ----------
  266.    Use this program at your own risk.  There are no warranties either
  267.    express or implied.  The author will not be liable for any damages 
  268.    relating to the use of this product.
  269.  
  270.    PPT Version 1.0  -  File PPT.DOC                            Page 6
  271.    ------------------------------------------------------------------
  272.  
  273.  
  274.    Tutorial
  275.    --------
  276.  
  277.        Configuration
  278.        -------------
  279.        First, start the program by typing PPT.  If you are running
  280.        the non-registered evaluation version, you will first see an 
  281.        identification screen.  Press any key to continue to the main
  282.        menu.
  283.  
  284.        The first thing you should do with PPT is configure it for
  285.        your particular working environment.  From the main menu, select
  286.        "Configure System".  We will walk through each of the items on the
  287.        configuration submenu separately.  Select "General" first.
  288.  
  289.        General - The first item is "Swap to EMS".  PPT has a shell
  290.        to DOS feature.  When you shell out, PPT is swapped out of 
  291.        memory so that you will have the maximum amount of memory to
  292.        work with while shelled.  Enter "Y" here if you want the system
  293.        to swap to expanded memory (when available).
  294.  
  295.        The "Alt Swap Path" indicates where PPT will be swapped if you
  296.        enter "N" to the previous field, or if not enough expanded memory
  297.        is available.  You may enter multiple paths here.  The syntax is
  298.        the same as the DOS PATH environment variable.
  299.  
  300.        Enter "Y" to "Bypass Welcome" if you wish to bypass the welcome
  301.        screen when PPT starts up.  This feature is only active if you
  302.        have registered the program.
  303.  
  304.        "Shell Prompt" allows you to set the command prompt which will be
  305.        in effect when you shell to DOS.  Same syntax as the DOS PROMPT
  306.        command.  You may use an "@" file if you have a long prompt that
  307.        won't fit in the provided space.
  308.  
  309.        If you need to back up and reenter a field, press Shift-Tab.
  310.        If you want to escape from the input screen without processing, 
  311.        press ESC.
  312.  
  313.        After you have entered all items, you will get a confirmation
  314.        prompt at the bottom of the screen.  Enter "Y" if you are satisfied
  315.        with your input.  Enter "N" to reenter.  You may press F10 (the
  316.        accept or GO key) at any time to immediately process all screen
  317.        data.  This is a standard feature on all input screens.
  318.  
  319.        After you have finished this screen, select "Editors / Viewers"
  320.        from the configuration menu.
  321.  
  322.    PPT Version 1.0  -  File PPT.DOC                            Page 7
  323.    ------------------------------------------------------------------
  324.  
  325.  
  326.        Editors / Viewers - One of PPT most powerful features is the 
  327.        ability to jump directly from one of PPT' analyses to the
  328.        corresponding line in your source code, using your favorite
  329.        editor or viewer programs.  This input screen is where you set
  330.        up the link to those programs.  There are 2 fields for each program.
  331.        The first is the name of the program, which will show up next to
  332.        the appropriate function key on the output screen for each module.
  333.        
  334.        The 1st editor/viewer program is invoked in each module by pressing
  335.        the ENTER or F3 key.  The 2nd editor/viewer program is invoked by
  336.        pressing the F4 key.  One approach to these fields would be to set
  337.        up one to use a simple viewer or browser program which would load 
  338.        very quickly for one of the programs, and a full-fledged editor for 
  339.        the other.
  340.  
  341.        
  342.        The "Command to invoke" field is where you enter the command which
  343.        will start your editor/viewer program with the appropriate file and
  344.        at the desired line number.  In this field, enter a "%s" where the
  345.        file name should go, and enter "%ld" where the line number should
  346.        go.
  347.  
  348.        For examples, we have used Vern Buerg's famous LIST program as the
  349.        default for editor/viewer 1, and the BRIEF editor as the default
  350.        for editor/viewer 2.  Press the HELP key (F1) to see some examples 
  351.        for other programs.  Be sure and enter a fully qualified path if
  352.        your program is not in your DOS PATH environment variable.
  353.  
  354.        Next, select "Drives" from the configuration menu.
  355.  
  356.        The "Drives Usage" module of PPT allows you to see at a glance
  357.        the available drive space for a number of logical drives at once.
  358.        Up to 15 logical drives can be specified for each of 5 different
  359.        scenarios.  One typical use would be to set up one scenario to
  360.        display your local drives, and another to display network drives.
  361.        
  362.        For each scenario, enter the drive letters you want displayed.
  363.        You may put spaces between the letters, but it is not necessary.
  364.        The last field, "Default Display", will present a pop-up window
  365.        and allow you to select either "Numeric" or "Graphic" as the
  366.        default display mode.  The "Drives Usage" module allows you to
  367.        toggle easily between the two.  This field merely indicates which
  368.        mode will be active when you first enter the module.
  369.  
  370.        That's it!  You're all set to begin your test drive.  Let's start
  371.        with the search module.
  372.  
  373.    PPT Version 1.0  -  File PPT.DOC                            Page 8
  374.    ------------------------------------------------------------------
  375.  
  376.  
  377.        Text / C Identifier Search
  378.        --------------------------
  379.        This module allows you to search across a number of source modules
  380.        for a specific C identifier or text string.  For this illustration, 
  381.        we will be using the the three sample C source files: LIST1.C, 
  382.        LIST2.C, LIST.H.
  383.  
  384.        Choose Text / C Identifier Search from the main menu.
  385.  
  386.        The first field on the input screen is where you enter the actual
  387.        identifier or text you will want to search for.  You may enter up
  388.        to ten different identifiers/strings to search for at once.  If more
  389.        than one is entered they should be space delimited.  You cannot 
  390.        search for identifiers and text in the same pass.  Text items with
  391.        embedded blanks should be enclosed within double quotes.  Wildcards
  392.        are supported for text searches.  "@" files are supported.  If you
  393.        want to search for a C structure element, enter it as
  394.        "structure.element", which will report all occurrences of both
  395.        "structure.element" and "structure->element".
  396.  
  397.        Note: Try F1-Help while in this input screen.  It explains all
  398.        input fields in detail.
  399.  
  400.        For our illustration enter the following for Text/Identifier:
  401.  
  402.            ESC fgetbyte icase noaccess
  403.  
  404.        For Search Files, enter:
  405.  
  406.            LIST*.C LIST.H
  407.  
  408.        For Text Or Identifier Search you are presented a pop-up screen.
  409.        The cursor should be highlighting "Identifier Search".  Press return
  410.        to accept this.
  411.  
  412.        For Case Sensitive, enter "Y".
  413.  
  414.        For Scan Include Files, enter "N".  If you enter "Y", PPT will
  415.        search all included header files automatically.  However, unless you
  416.        have a Borland C compiler installed, you will likely get a warning
  417.        message that PPT cannot find one of the included .H files.  For
  418.        this tutorial, you can just ignore that message.  Scanning include
  419.        files is a very powerful feature which allows you to determine very
  420.        quickly where and how a particular macro is defined.
  421.  
  422.        Press enter at the confirmation message to start the search.  A
  423.        progress window will appear while the search is progressing.  When
  424.        the search is done the output display will appear.
  425.  
  426.    PPT Version 1.0  -  File PPT.DOC                            Page 9
  427.    ------------------------------------------------------------------
  428.  
  429.  
  430.        The output display has the date and time of the search in the upper
  431.        left hand corner.  The display itself is a scrollable listing of
  432.        all occurrences of your search identifiers, organized by module.
  433.        Actual occurrences of each identifier are shown in yellow for easy
  434.        visual identification.  You can scroll through the display using
  435.        the normal cursor keys.
  436.    
  437.        Press END to get to the bottom of the display.  You will see a 
  438.        summary of the number of files and lines scanned, and the number
  439.        of occurrences found of each search identifier.
  440.  
  441.        Scroll up and down using the arrow keys.  Notice that when the
  442.        cursor bar is on an actual line of code, the name of the source
  443.        module appears in the upper right hand corner of the display.
  444.  
  445.        The "ENTER/F3" key on the bottom legend should be displaying the
  446.        name of your first editor/viewer program that you configured earlier.
  447.        The "F4" key should be displaying the name of your second editor/
  448.        viewer program.  These keys allow a direct link to your source code,
  449.        and are one of the most powerful features of PPT.
  450.  
  451.        Move the cursor bar to the first source line under LIST2.C, the 
  452.        line that reads:
  453.  
  454.            39  extern char *noaccess;
  455.  
  456.        Now press ENTER or F3.  If you have configured your editor/viewer
  457.        programs properly, your first editor/viewer program should come up,
  458.        with LIST2.C loaded, and placed on line 39.  (If your program does
  459.        not support positioning on a specific line, you may be at the top of
  460.        the module instead.)  Work inside this program as you normally would.
  461.        When you exit from the editor/viewer, you will be back in PPT.
  462.  
  463.        Try pressing F4.  The same thing should happen with your second
  464.        editor/viewer program as happened when you pressed ENTER or F3.
  465.        If you have any problems with this, review the configuration
  466.        section of this documentation.
  467.  
  468.        Let's suppose you want to produce a printed report from this search,
  469.        but that you're not interested in the prototypes that showed up
  470.        in the output.  Position the cursor on the following line in LIST.H:
  471.  
  472.            96  void search_setup(unsigned char *pat, int plen, int icase);
  473.  
  474.        Press the DEL key to hide this line.  Notice in the lower right hand
  475.        corner, an "HR" icon has appeared, indicating that there are "hidden
  476.        records".  To restore this record, press INS.  The "HR" icon will
  477.        disappear.  If you have hidden several records, INS will restore them
  478.        one at a time.  To restore them all at once, press CTRL-I.
  479.  
  480.    PPT Version 1.0  -  File PPT.DOC                           Page 10
  481.    ------------------------------------------------------------------
  482.  
  483.  
  484.        To produce a printed report of this search, press F2.  The input
  485.        screen is fairly self explanatory.  Enter up to 4 lines of title.
  486.  
  487.        For Output File or Printer Device, enter a valid printer port, or
  488.        a file name to send output to.  If necessary, change the default
  489.        values for Lines Per Page and Left Margin.  Press F10 to start the
  490.        report, or press enter until you get to the confirmation message.
  491.  
  492.        Now, press ESC to get back to the input screen.  From here, pressing
  493.        F9 will return you to the output display, but for the moment, stay
  494.        here.
  495.    
  496.        NOTE: THE FOLLOWING DISCUSSES SAVED SCENARIOS WHICH ARE ONLY
  497.              ACTIVE IN THE REGISTERED VERSION.
  498.  
  499.        Notice the F2 and F3 keys for loading and saving scenarios.  Each 
  500.        time you execute a search, it overwrites the previous scenario, 
  501.        UNLESS you have SAVED the previous scenario.  To save a search 
  502.        scenario, press F3.  Press F3 now.  Now, press F2.  What you see is 
  503.        a screen showing the scenarios you have saved.  You press enter to
  504.        load a saved scenario, or DEL to remove one.  You can store as many
  505.        scenarios as you want, limited only by available disk space.  As a
  506.        practical matter however, you will want to remove scenarios you no
  507.        longer need, since doing so will improve performance.
  508.  
  509.        Try some more searches on your own.  Try some text searches as well
  510.        as identifier searches.  Try setting the Case Sensitive field to "N".
  511.        Try saving and loading multiple scenarios.  Press F1 for help, go
  512.        to the Help Index, and read about "@ Files".  Try using one for the
  513.        Search Files field.  Try starting a search and pressing ESC while
  514.        it's still in progress.  Notice how you can stop immediately, and
  515.        still not lose the results of your search up to that point.
  516.  
  517.        Exit from PPT using ALT-X (quick exit).  Now start it up again
  518.        using the command "PPT SV" which will take you directly to the
  519.        search viewer.  Notice that the cursor is still on the line it was
  520.        when you exited!  Most fields in PPT are "sticky" in this way.
  521.        They remember where you were when you left, and what your input
  522.        choices were the last time you used each module.
  523.  
  524.    PPT Version 1.0  -  File PPT.DOC                           Page 11
  525.    ------------------------------------------------------------------
  526.  
  527.  
  528.        Drives Usage
  529.        ------------
  530.        Select Drives/File Usage from the main menu.  You will see a usage
  531.        display for the logical drives you entered for scenario 1 when you
  532.        configured the system.  If you selected "graphic" for the default
  533.        display, the amount of disk space used will appear as a subdued
  534.        green bar, and the amount free will appear as a bright green bar.
  535.        You will also see the amount free as a numeric value, and as a
  536.        percent of total space available.  Totals for all drives appear
  537.        at the bottom.
  538.  
  539.        If you selected "numeric" for the default display, the graphic bar
  540.        will be replaced by numeric fields, as well as an indication of the
  541.        drives volume label.  Toggle the F2 key to see the difference between
  542.        the numeric and graphic display.
  543.  
  544.        Try toggling through your scenarios by pressing F5 repeatedly.
  545.        This procedure will have no effect unless you set up more than one
  546.        scenario.
  547.  
  548.        Press F3 to display the number of files on each logical drive.
  549.        This can take a bit of time on a drive with a very large number of
  550.        files.  You can press ESC at any time to interrupt the count.
  551.  
  552.    PPT Version 1.0  -  File PPT.DOC                           Page 12
  553.    ------------------------------------------------------------------
  554.  
  555.  
  556.        Search and Replace Identifier
  557.        -----------------------------
  558.        This module allows you to replace the occurrence of a particular
  559.        C identifier (variable, function name, macro, etc.) with another,
  560.        across multiple source modules.  The interface is very similar to
  561.        the Text / C Identifier Search module.  You should be sure and
  562.        walk through that example before this one.
  563.        
  564.        For this illustration, we will be using the sample files LIST1.C 
  565.        and LIST2.C.  We are going to replace all instances of the variable
  566.        "i" with "I" (upper case).  
  567.        
  568.        Choose Search and Replace from the main menu.
  569.  
  570.        For Old Identifier, enter "i" (without the quotes).  
  571.        
  572.        For New Identifier, enter "I".  
  573.        
  574.        For Modules To Update, enter LIST*.C.
  575.  
  576.        For Update Include Files, enter "N".
  577.  
  578.        For Backup Files Extension, you can accept the default BAK, or
  579.        enter another extension up to 3 characters long.  PPT makes
  580.        automatic backups of your files before changing them.  Even so, 
  581.        if you are the overly-cautious type (like I am!), you may want to
  582.        make copies of your source files yourself, even though PPT will
  583.        also.
  584.  
  585.        After the modules are searched, you will see a scrollable display
  586.        virtually identical to the one in the Text / C Identifier Search
  587.        module.  Occurrences of "i" will be highlighted.  Function keys
  588.        F2, F3/ENTER, and F4 operate as they do in the in the previous
  589.        search module.  F5 starts the update process.  Press F5 now.
  590.  
  591.        You will see several progress displays during the update.  When 
  592.        it is finished, a message window regarding backup files will be
  593.        displayed.  Press enter, and you will be returned to the input
  594.        screen.
  595.  
  596.        Now let's look at the changed files.  This is a good time to try
  597.        a couple of the hotkeys.  ALT-F3 and ALT-F4 are active everywhere
  598.        in the system, and allow you to bring up either of your editor/
  599.        viewer programs, with a file which you specify through an input
  600.        window.
  601.  
  602.    PPT Version 1.0  -  File PPT.DOC                           Page 13
  603.    ------------------------------------------------------------------
  604.  
  605.  
  606.        Press ALT-F3 now.  Enter the file name LIST2.C and press enter.
  607.        You will be placed in your first editor/viewer program with LIST2.C
  608.        loaded.  Scroll around and satisfy yourself that all occurrences of
  609.        "i" are now "I".  When you exit your editor/viewer, you will be
  610.        back in PPT.
  611.    
  612.        Now let's see if the backup files actually got created.  Press
  613.        ALT-D to shell out to DOS.  Type the command DIR *.BAK (or whatever
  614.        extension you selected for the backup files).  You should see
  615.        entries for LIST1.BAK, and LIST2.BAK.  
  616.  
  617.        Notice while you're shelled out to DOS that your prompt has
  618.        changed to whatever you set it up to be during configuration.
  619.        Just type EXIT to get back to PPT.
  620.  
  621.        That's all there is to it.  Imagine the benefit of replacing a
  622.        variable name in 10 or 20 modules (or more!), instead of having
  623.        to do it file by file with your editor.
  624.  
  625.    PPT Version 1.0  -  File PPT.DOC                           Page 14
  626.    ------------------------------------------------------------------
  627.  
  628.  
  629.        Function Analyzer
  630.        -----------------
  631.        This module allows you to interactively peruse the function
  632.        hierarchy (i.e., call structure) of a program.  I have found it
  633.        extremely useful for analyzing someone else's source code, as well
  634.        as my own code that I haven't looked at for a while.  For purposes
  635.        of the tutorial, we will again be using the LIST1.C and LIST2.C
  636.        modules.
  637.  
  638.        Choose Function Analyzer from the main menu.
  639.  
  640.        For Source Modules, enter LIST*.C.
  641.  
  642.        The Exclude Files field allows you to enter the name of a text
  643.        file which has a list of functions you want to exclude from the
  644.        analysis.  A typical use would be to exclude functions from the
  645.        run-time library, so you can focus on application calls only.
  646.        A template file for this purpose is included and named RTLIB.EXC.
  647.        You may want to browse through it and edit it for your own purposes.
  648.        For now, leave this field blank.
  649.  
  650.        The Start Function field allows you to specify which function to
  651.        start the hierarchy analysis with.  For now, accept the default of
  652.        "main", so we can examine the entire call structure.  If at some
  653.        point you are trying to analyze an extremely large project and run
  654.        out of memory, you can enter a lower-level function instead of
  655.        "main", which will require less memory to analyze.
  656.  
  657.        The Function Headers field will display a pop-up screen with the
  658.        following choices:
  659.  
  660.                1 - Do Not Generate
  661.                2 - Generate with /* */
  662.                3 - Generate with //
  663.                4 - Remove
  664.  
  665.        Function headers are comments that are generated automatically and
  666.        placed in your source code just prior to each function declaration.
  667.        The comment indicates what other functions call the one documented.
  668.  
  669.        Choice (1) will not generate any comment headers.  Choice (2) will
  670.        generate them with traditional C comment delimiters (/* */).
  671.        Choice (3) will generate them with single line comment delimiters
  672.        (//), and Choice (4) will remove headers already in your code.
  673.  
  674.        For now, accept the default of Do Not Generate.  The next field,
  675.        Backup Files Ext. will be deactivated.  Backup files are only
  676.        generated if you choose an option that modifies your source code.
  677.  
  678.    PPT Version 1.0  -  File PPT.DOC                           Page 15
  679.    ------------------------------------------------------------------
  680.  
  681.  
  682.        In the call tree display, lower level functions are indented to
  683.        show the hierarchy.  You can control the amount of indentation
  684.        with the field Spaces To Indent Each Level In Call Tree.
  685.    
  686.        The call tree display can optionally include the nesting level
  687.        (where main is level 1, functions called by main are level 2, etc).
  688.        For now, leave the field Show Nesting Level In Call Tree as "N".
  689.  
  690.        Show Duplicate Function Calls controls whether each and every call
  691.        of a function by another is shown in the call tree, or just the
  692.        first occurrence is shown.  Suppose you have a function called
  693.        printem() which calls printf() 5 times.  With Show Duplicate
  694.        Function Calls set to "N", only the first occurrence will be shown.
  695.        If you set it to "Y", all occurrences will be shown.  Setting this
  696.        field to "Y" may require significantly more time and memory for
  697.        the analysis.  For now, leave it set to "N".
  698.  
  699.        After you accept the confirmation message, the analysis will begin.
  700.        When it's finished, you will be placed in a scrollable display of
  701.        the call hierarchy.
  702.  
  703.        The cursor will be on "main" at the top of the display.  Scroll
  704.        through display using the arrow keys and note the source file
  705.        name which appears (and changes) in the upper right corner.  This
  706.        indicates which source file the highlighted call appears in.  The
  707.        number in the left hand column is the line number in the source
  708.        file where the actual call appears.
  709.  
  710.        The ENTR/F3 and F4 keys work as they do in the search modules to
  711.        link you directly to your source code.  Cursor down to the call to
  712.        get_video_mode and press ENTR or F4.  You should be in your editor/
  713.        viewer program with LIST2.C loaded, and positioned at line 601,
  714.        which is where the actual call to get_video_mode occurs.
  715.  
  716.        Exit out of your editor/viewer program back to the PPT display.
  717.        Let's try out a few of the other function keys.
  718.  
  719.        Press F6.  This brings up a display of all functions encountered
  720.        during the analysis, with the cursor on the same function that is
  721.        highlighted in the call tree, in this case, get_video_mode.  Press
  722.        ENTR/F3 or F4 here and you will link to your source code where
  723.        get_video_mode is actually defined (as opposed to where it was 
  724.        called).  Now go back to PPT.
  725.  
  726.        You can jump quickly to a function in this function list by simply
  727.        typing in the function name.  As you type, the cursor will zero-in
  728.        on the appropriate name.  Try typing "showfile" to see how this
  729.        works.
  730.  
  731.        Let's look at the other 2 split screens that are available.  You can
  732.        exit this split screen by pressing ESC, a left or right arrow, or
  733.        another function key.  Press ESC to clear the split screen.
  734.  
  735.    PPT Version 1.0  -  File PPT.DOC                           Page 16
  736.    ------------------------------------------------------------------
  737.  
  738.  
  739.        Place the cursor on one of the calls to "lseek".  Now press F8.
  740.        This split screen displays all the functions which call lseek.
  741.        Place the cursor on "find_text" and press ENTR/F3 or F4.  You will
  742.        be in LIST1.C at line 603, where lseek is called by find_text.
  743.    
  744.        Now, press F10.  This final split screen shows all functions which
  745.        are not directly called anywhere in the program.  That is, they are
  746.        either not called at all, or they are called indirectly through a
  747.        pointer.  "main" will always appear in this list, since it is called
  748.        by the operating system and not the program.  In our example, there
  749.        are no other functions that are not directly called.
  750.  
  751.        Press ESC to exit the split screen display.
  752.  
  753.        The F5, F7, and F9 function keys are used to quicly locate a function
  754.        call in the hierarchy.  Press F7.  A pop-up window appears where
  755.        you can type in a function name.  Type in "fgetbyte" and press enter.
  756.        The cursor will jump forward to the first occurrence of that function
  757.        call.  Press F5 to search backward, and F9 to search forward.
  758.  
  759.        There is a second legend with more key functionality.  Press Ctrl-M
  760.        to toggle the legend.
  761.  
  762.        You can hide records in the hierarchy display in the same way you
  763.        do in the search modules.  The difference is that pressing DEL will
  764.        hide the highlighted function, and ALL FUNCTIONS CALLED BY IT.  To
  765.        see how this works, first press HOME to the position the cursor at
  766.        the top of the display.  Now cursor down to the first call to
  767.        save_cursor, and press DEL.  Notice how the call to geninterrupt 
  768.        also disappears.  To restore hidden lines one at a time, press INS.
  769.        To restore them all at once, press Ctrl-I.
  770.  
  771.        This module provides the unique capability of showing the direct
  772.        call path to a particular function.  Press PageDown a few times to
  773.        position the cursor on the "read" call at line 262 in LIST2.C.
  774.        Now press Ctrl-P.  The path to the highlighted call is immediately
  775.        "collapsed" so you can see the direct route to this call from main.
  776.        You can restore the display by pressing Ctrl-I.
  777.  
  778.    PPT Version 1.0  -  File PPT.DOC                           Page 17
  779.    ------------------------------------------------------------------
  780.  
  781.  
  782.        Now press Ctrl-M to toggle back to the main legend.  The last
  783.        function key to look at is F2 which generates a printed report.
  784.        Press F2 now.  A pop-up appears permitting you to select a 
  785.        combination of 3 reports: (1) The Call Tree Report (a printed
  786.        version of the hierarchy display), (2) The Called-By Report (a 
  787.        printed version of F8), and (3) The Not-Called Report (a printed 
  788.        version of F10).
  789.  
  790.        Enter "Y" for all 3 reports.  If you have a printer capable of
  791.        printing the same line drawing characters which appear in the
  792.        call tree display, enter "Y" to Print Line Chars.  If you have
  793.        an HP Laserjet printer or compatible, answer "Y" to Download HP
  794.        Font, and a special soft font will be automatically downloaded
  795.        which contains the appropriate line drawing characters.
  796.  
  797.        You are now presented with the same report generation input screen
  798.        that we saw in the search module tutorial.  Fill it out as
  799.        appropriate.  When the report is finished, you will be back at the
  800.        call tree display.  
  801.  
  802.        Let's look at a couple of features that we skipped over in this
  803.        first example.  Press ESC to return to the Function Analyzer Input
  804.        screen.
  805.  
  806.        Let's run the same analysis with the following changes:
  807.            For Exclude Files, enter "LIST.EXC".
  808.            For Func Headers, enter "2 - Generate with /* */".
  809.            For Show Nesting Level In Call Tree, enter "Y".
  810.  
  811.        Press F10 when ready.  You'll notice some additional progress
  812.        messages relating to updating your source files with comment headers,
  813.        and the creation of backup files.
  814.  
  815.        When you get to the call display, you will notice a couple of
  816.        differences.  First, each function name is preceded by a number
  817.        indicating the nesting level of the call.  This can be very useful
  818.        in long, deeply nested programs.  Also, if you scroll through the
  819.        display, you'll notice that it's much shorter than our previous 
  820.        example, and that some functions seem to be "missing".  This is
  821.        because we excluded from the analysis the files listed in the
  822.        file LIST.EXC.  Sometimes eliminating low-level run-time library
  823.        functions can give you a quicker overall feel for the structure of
  824.        the program.
  825.  
  826.        Now, press F6 to get a list of all functions analyzed.  Cursor
  827.        down to the function "display_line", and press ENTR/F3 or F4.
  828.        When in your editor/viewer program, look just ahead of the 
  829.        display_line definition to see the comment header inserted.  It
  830.        indicates that this function is called by showfile in LIST1.C,
  831.        and by fill_window in LIST2.C.  Using this auto-doc feature can
  832.        significantly enhance your productivity when analyzing new source
  833.        code.
  834.        
  835.    PPT Version 1.0  -  File PPT.DOC                           Page 18
  836.    ------------------------------------------------------------------
  837.  
  838.  
  839.        Now get back to the Function Analyzer input screen.  The F2 and
  840.        F3 keys for saving and loading scenarios work exactly like they
  841.        do in the search module.  Refer to that section for a detailed
  842.        explanation.
  843.  
  844.    PPT Version 1.0  -  File PPT.DOC                           Page 19
  845.    ------------------------------------------------------------------
  846.  
  847.  
  848.        Set Files Date / Time
  849.        ---------------------
  850.        This module allows you to set the date and time stamp to any values
  851.        you choose, and works on multiple files.  
  852.        
  853.        Choose Set Files Date/Time from the main menu.
  854.  
  855.        The input form has fields for the files to modify, and the date and
  856.        time to set them to.  The date and time are set by default to the
  857.        date and time you entered the module.
  858.  
  859.        The files specification can be include a relative or absolute
  860.        pathname, as well as the wildcard characters '*' and '?'.  Multiple
  861.        groups of file specs can be entered if space delimited.  "@" files
  862.        are supported.  Try entering "LIST*.*" which will modify the 3 C
  863.        source files that are included as sample files for the tutorial.
  864.  
  865.        Enter a date in the format "mm/dd/yy", but don't enter the slashes,
  866.        they are pre-entered.
  867.  
  868.        Enter a time in the format "hh:mm:ss".  Use military time (24 hour
  869.        clock) for hours after 12:00 noon.  You must enter the ":" character.
  870.        Seconds are optional.
  871.  
  872.        Press return in response to the confirmation message to actually
  873.        perform the update.  You will see a result window which will indicate
  874.        the number of files actually modified.
  875.  
  876.    PPT Version 1.0  -  File PPT.DOC                           Page 20
  877.    ------------------------------------------------------------------
  878.  
  879.  
  880.    Miscellaneous Features
  881.    ----------------------
  882.  
  883.        Startup Options
  884.        ---------------
  885.        The program is started by typing PPT at the command line.  You
  886.        can rename this program, but you CANNOT rename any of the other
  887.        .EXE files which are called by PPT.EXE.
  888.  
  889.        PPT supports a number of command line options for quickly jumping
  890.        to a particular module:
  891.  
  892.           PPT C    Go directly to the Configuration menu.
  893.           PPT D    Go directly to the Drives Usage module.
  894.           PPT F    Go directly to the Function Analyzer input screen.
  895.           PPT FV   Go directly to the Function Analyzer output viewer.
  896.           PPT L    Go directly to the Set Files Date/Time module.
  897.           PPT R    Go directly to the Search and Replace input screen.
  898.           PPT RV   Go directly to the Search and Replace output viewer.
  899.           PPT S    Go directly to the Text / C Ident Search input screen.
  900.           PPT SV   Go directly to the Text / C Ident Search output viewer.
  901.  
  902.        The command line options are NOT case sensitive.
  903.  
  904.  
  905.        @ Files
  906.        -------
  907.        A number of the input fields in various modules support "@" files.
  908.        Where this support is indicated (use F1-Help from the input screen), 
  909.        the user may put a list of the requested items in a text file and 
  910.        enter the name of the text file (with a path component if necessary) 
  911.        prefixed with an "@" for the input field.  The "@" file should have 
  912.        one item per line.  For file specifications, wildcard characters "*" 
  913.        and "?" are supported.  Blank lines and lines that begin with a ";" 
  914.        are ignored.
  915.  
  916.        For example, the Function Analyzer module has an input field for
  917.        the source files to be analyzed.  Rather than list all the files
  918.        individually in this field, the user could enter "@ACCTG.FLS,
  919.        where the file ACCTG.FLS looks as follows:
  920.  
  921.            ACCTG.FLS
  922.            ---------
  923.            ; Source files for the Accounting Project
  924.            C:\ACCTG\*.C
  925.            C:\ACCTG\*.H
  926.            C:\ACCTG\LIB\*.C
  927.  
  928.    PPT Version 1.0  -  File PPT.DOC                           Page 21
  929.    ------------------------------------------------------------------
  930.    
  931.  
  932.        Hotkeys
  933.        -------
  934.        PPT supports a number of hotkeys:
  935.  
  936.            Alt-A       Dedication and acknowledgments.
  937.            Alt-D       Shell out to DOS.
  938.            Alt-F       Jump to Function Analyzer viewer.
  939.            Alt-F3      View a file with F3 editor/viewer (1).
  940.            Alt-F4      View a file with F4 editor/viewer (2).
  941.            Alt-H       Display the hotkey help pop-up.
  942.            Alt-M       Jump to main menu.
  943.            Alt-R       Jump to Search and Replace viewer.
  944.            Alt-S       Jump to Text / C Ident Search Viewer.
  945.            Alt-T       Display date and time.
  946.            Alt-X       Quick exit to DOS.
  947.  
  948.  
  949.        Help System
  950.        -----------
  951.        Context-sensitive help is available everywhere in the system by
  952.        pressing F1.  Each help screen has additional choices at the
  953.        bottom of the screen, allowing you to jump to the help topic index,
  954.        page forward and backward, and exit the help system.  There may
  955.        also be choices for help on related topics.  You can cycle through
  956.        these choices with the cursor keys.  You can also select them by
  957.        pressing the appropriate (highlighted) hotkey.
  958.  
  959.        Pressing ESC in a help screen will back you up to the previous
  960.        screen.  Pressing F10 will immediately exit the help system.
  961.  
  962.    PPT Version 1.0  -  File PPT.DOC                           Page 22
  963.    ------------------------------------------------------------------
  964.    
  965.  
  966.    Troubleshooting
  967.    ---------------
  968.  
  969.        Limitations
  970.        -----------
  971.  
  972.            Drives Usage
  973.            ------------
  974.            The SIZE and USED fields cannot accurately report an amount
  975.            of disk space larger than 268 megabytes.
  976.            
  977.  
  978.            Function Analyzer
  979.            -----------------
  980.            The function analyzer requires syntactically correct C code.
  981.            If your code does not compile cleanly, PPT can hang.
  982.            The function analyzer does not currently recognize "#if"-type
  983.            statements.  If you get an unbalanced braces or parentheses
  984.            message (although your code compiles without errors), look
  985.            for a brace or parenthesis imbalance within your "#if"
  986.            directive.
  987.  
  988.            Maximum number of modules you can analyze is 150.
  989.            Maximum number of function references is 5000.
  990.            Function names cannot be greater than 30 characters.
  991.            You can specify no more than 10 exclude files.
  992.            There can be no more than 1350 exclude functions.
  993.            The maximum length of a C source line is 1024 bytes.
  994.  
  995.            The function analyzer's real-world limitations are directly
  996.            dependent on the amount of available conventional memory.
  997.            If you get a message indicating there is not enough memory
  998.            to complete the analysis, try increasing your available
  999.            memory.  You should also answer "No" to "Show Duplicate
  1000.            Function Calls" on the input screen.  You could also try
  1001.            "excluding" more functions.  You can also subdivide your
  1002.            analysis into a number of smaller analyses with lesser scope.
  1003.  
  1004.  
  1005.        Resetting the Database
  1006.        ----------------------
  1007.        It's possible under certain conditions for the database in PPT to
  1008.        become corrupted.  To reset it, run the program RESETDB.EXE.  If you
  1009.        run it without any command line parameters, it will reset your
  1010.        database, but leave your configuration choices intact.  If you run it
  1011.        with a "-d" command line parameter, the original distribution default
  1012.        configuration will be restored.
  1013.  
  1014.